.\" $OpenBSD: EVP_CIPHER_CTX_init.3,v 1.3 2023/12/26 22:13:00 schwarze Exp $
.\" full merge up to:
.\" OpenSSL EVP_EncryptInit.pod 0874d7f2 Oct 11 13:13:47 2022 +0100
.\"
.\" This file is a derived work.
.\" The changes are covered by the following Copyright and license:
.\"
.\" Copyright (c) 2018, 2019, 2023 Ingo Schwarze <schwarze@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.\" The original file was written by Dr. Stephen Henson <steve@openssl.org>
.\" and Richard Levitte <levitte@openssl.org>.
.\" Copyright (c) 2000-2001, 2015 The OpenSSL Project.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\"
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\"
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in
.\"    the documentation and/or other materials provided with the
.\"    distribution.
.\"
.\" 3. All advertising materials mentioning features or use of this
.\"    software must display the following acknowledgment:
.\"    "This product includes software developed by the OpenSSL Project
.\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
.\"
.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
.\"    endorse or promote products derived from this software without
.\"    prior written permission. For written permission, please contact
.\"    openssl-core@openssl.org.
.\"
.\" 5. Products derived from this software may not be called "OpenSSL"
.\"    nor may "OpenSSL" appear in their names without prior written
.\"    permission of the OpenSSL Project.
.\"
.\" 6. Redistributions of any form whatsoever must retain the following
.\"    acknowledgment:
.\"    "This product includes software developed by the OpenSSL Project
.\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
.\" OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd $Mdocdate: December 26 2023 $
.Dt EVP_CIPHER_CTX_INIT 3
.Os
.Sh NAME
.Nm EVP_CIPHER_CTX_init ,
.Nm EVP_CIPHER_CTX_cleanup ,
.Nm EVP_Cipher
.Nd obsolete EVP cipher functions
.Sh SYNOPSIS
.In openssl/evp.h
.Ft void
.Fo EVP_CIPHER_CTX_init
.Fa "EVP_CIPHER_CTX *ctx"
.Fc
.Ft int
.Fo EVP_CIPHER_CTX_cleanup
.Fa "EVP_CIPHER_CTX *ctx"
.Fc
.Ft int
.Fo EVP_Cipher
.Fa "EVP_CIPHER_CTX *ctx"
.Fa "unsigned char *out"
.Fa "const unsigned char *in"
.Fa "unsigned int in_len"
.Fc
.Sh DESCRIPTION
.Fn EVP_CIPHER_CTX_init
is a deprecated function that could be used to clear a cipher context
on the stack before
.Vt EVP_CIPHER_CTX
was made opaque.
Calling it on a cipher context just returned from
.Xr EVP_CIPHER_CTX_new 3
has no effect.
Calling it on a cipher context that was already used leaks memory.
Instead, use
.Xr EVP_CIPHER_CTX_reset 3
or
.Xr EVP_CIPHER_CTX_free 3 .
.Pp
.Fn EVP_CIPHER_CTX_cleanup
is a deprecated alias for
.Xr EVP_CIPHER_CTX_reset 3 .
It clears all information from
.Fa ctx
and frees all allocated memory associated with it, except the
.Fa ctx
object itself.
.Pp
.Fn EVP_Cipher
exposes implementation details of the functions
.Xr EVP_CipherUpdate 3
and
.Xr EVP_CipherFinal 3
that should never have become part of the public API.
.Pp
If the flag
.Dv EVP_CIPH_FLAG_CUSTOM_CIPHER
is set for the cipher used by
.Fa ctx ,
behaviour depends on
.Fa in .
If that argument is
.Dv NULL
and
.Fa in_len
is 0, behaviour is similar to
.Xr EVP_CipherFinal 3 ;
if
.Fa in_len
is not 0, behaviour is undefined.
If
.Fa in
is not
.Dv NULL ,
behaviour is similar to
.Xr EVP_CipherUpdate 3 .
In both cases, the exceptions to the similarity are that arguments
and return values differ.
.Pp
If the flag
.Dv EVP_CIPH_FLAG_CUSTOM_CIPHER
is not set for the cipher used by
.Fa ctx ,
it encrypts or decrypts aligned blocks of data
whose lengths match the cipher block size.
It requires that the previous encryption or decryption operation
using the same
.Fa ctx ,
if there was any, ended exactly on a block boundary and that
.Fa in_len
is an integer multiple of the cipher block size.
If either of these conditions is violated,
.Fn EVP_Cipher
silently produces incorrect results.
For that reason, using the function
.Xr EVP_CipherUpdate 3
instead is strongly recommended.
The latter can safely handle partial blocks, and even if
.Fa in_len
actually is a multiple of the cipher block size for all calls,
the overhead incurred by using
.Xr EVP_CipherUpdate 3
is minimal.
.Sh RETURN VALUES
.Fn EVP_CIPHER_CTX_cleanup
returns 1 for success or 0 for failure.
.Pp
With
.Dv EVP_CIPH_FLAG_CUSTOM_CIPHER ,
.Fn EVP_Cipher
returns the number of bytes written to
.Fa out
for success or \-1 for failure.
Without
.Dv EVP_CIPH_FLAG_CUSTOM_CIPHER ,
it returns 1 for success or 0 for failure.
.Sh SEE ALSO
.Xr evp 3 ,
.Xr EVP_EncryptInit 3
.Sh HISTORY
.Fn EVP_Cipher
first appeared in SSLeay 0.6.5.
.Fn EVP_CIPHER_CTX_cleanup
first appeared in SSLeay 0.8.0.
.Fn EVP_CIPHER_CTX_init
first appeared in SSLeay 0.9.0.
All these functions have been available since
.Ox 2.4 .
.Sh CAVEATS
Checking the return value of
.Fn EVP_Cipher
requires unusual caution: zero signals success if
.Dv EVP_CIPH_FLAG_CUSTOM_CIPHER
is set or failure otherwise.
